<!--
    Licensed to the Apache Software Foundation (ASF) under one or more
    contributor license agreements.  See the NOTICE file distributed with
    this work for additional information regarding copyright ownership.
    The ASF licenses this file to You under the Apache License, Version 2.0
    (the "License"); you may not use this file except in compliance with
    the License.  You may obtain a copy of the License at
  
       http://www.apache.org/licenses/LICENSE-2.0
  
    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
-->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>

<head>
<title>Porting Layer Notes</title>
</head>

<body>

<h3>0. Preliminary Notes</h3>

The porting layer is a work-in-progress and is not yet shaped nicely.
Currently it consists of quite heterogeneous pieces (APR extensions, logger, 
encoder, utility templates etc) which do not form unified interface.


<h3>1. Design  Notes</h3>

The porting layer design adheres to concepts of APR (<a href="http://apr.apache.org/docs/apr/">Apache
Portable Runtime libraries</a>), specifically:
<ul>
<li>Explicit memory management based on pools
<li>Consistent error reporting approach via returned status value
<li>Incomplete types to enforce platform abstraction
</ul>
Detailed APIs mainly follow the APR standard, but there may not be strict correspondence
in signatures. Pure C should be used for implementation.

<!-- The below info is outdated
<h4>Using APR binaries directly</h4>
Harmony defines its own headers aligned with APR, but does not wrap APR functions
in code (no delegating calls). Instead, signatures are mapped directly to APR functions
where possible - via a set of defines, as follows:
<pre>
#define port_allocator_create(allocator) apr_allocator_create(allocator)
#define port_allocator_destroy(allocator) apr_allocator_destroy(allocator)
</pre>
<p>In this case, no run-time performance penalty is incurred. </p>
<p>The current approach has several significant advantages over using APR headers
  directly: </p>
<ul>
<li>Flexibility to switch the portlib implementation to j9 or any other, including
  our own, at any time. In other words, the  internal portlib
  issues are hidden from API customers.
<li>Extensions to APR; currently, over 20 functions are implemented that are not
  part of APR. 
<li>Consistent naming of the whole porting API.
<li> Simplified bug fixing and tuning: several APR functions have been
  encountered that have flaws or are not suitable for DRLVM; these functions are
  easily replaced with Harmony's extensions.The same is applicable for VAV.
<li>Easier potential support for dynamic linking or multi-VM support with Harmony
  headers than with APR is: Harmony can organize VTables easier, unlike APR, which
  sometimes uses defines instead of real functions.
<li>Common headers to unify porting module build system with the DRLVM system: the
  APR build organization is completely different in that it uses different sets of
  headers for each platform, with specific defines. 
<li>Clearly identified subset of APR functionality, which is actually used, which
  may  be helpful for further VM porting.
</ul>

The key drawbacks of the current approach: 
<ul>
<li>Need for duplication of headers and documentation, though  redirection links
  to APR docs can be used to work around this flaw. 
<li>Potential compatibility issues with future APR development, for instance, on
  extension boundaries.
<li>Potential confusion in the open community, especially for those experienced in
  APR applications.
</ul>

-->

<h3>2. Directory structure</h3>

Porting functionality is split to several groups: atomics, file I/O, mempools, etc.
Each group has a base directory, which contains subdirectories with actual code.
These subdirectories are named after the platforms and/or architectures they are
compiled on. If there is a strong dependency on both OS and machine architecture,
the subdirectory name should combine both. The current directory structure looks
as follows:
<pre>port
|->build
|->doc
|->include
|  ->tl
 ->src
  |->atomic
  | |->linux
  | |->linux_ipf
  |  ->win
  |->barriers
  |  ->linux_ipf
  |->crash_handler
  | |->em64t
  | |->ia32
  | |->include
  | |->ipf
  | |->linux
  | |  ->include
  |  ->win
  |->disasm
  | |->linux
  |  ->win
  |->encoder
  |  ->ia32_em64t
  |->file_io
  | |->linux
  |  ->win
  |->lil
  |  ->em64t
  |->logger
  |->malloc
  |->memaccess
  | |->linux
  |  ->win
  |->misc
  | |->linux
  |  ->win
  |->modules
  | |->linux
  |  ->win
  |->signals
  | |->include
  | |->linux
  |  ->win
  |->thread
  | |->linux
  |  ->win
  |->time
  |->tl
   ->vmem
    |->linux
     ->win	 
</pre>
<p>
Public headers are kept in a separate base directory named <code>include/</code>.
Implementation headers may be kept in the source directories.

<h3>3. Memory management</h3>

The port layer contains wrappers for standard memory allocation functions in the <code>port_malloc.h</code> file.
They are presented as defines with names like <code>STD_MALLOC</code> for malloc, <code>STD_FREE</code> for
free etc. By default, they are simply equal to relative functions, but if <code>_MEMMGR</code> is
defined, they are replaced with another set of functions like <code>port_malloc</code>, <code>port_free</code> etc.
These functions provide additional functionality at the expense of lower performance.
<p>
Newly provided features:

<ul>
<li>Report allocation and de-allocation log
<li>Check and report double free calling
<li>Report not freed memory at VM shutdown
<li>Provide precise info about currently used memory via the <code>java.lang.management</code> interface
<li>Provide separate memory allocation for the stress running conditions, like after
  crash handler occurring
</ul>

<h4>Instructions on using these features</h4>
<p>To switch on allocation and de-allocation logging, define the <code>_MEMMGR_LOG</code> macro.
  This macro also enables double free calling notifications. </p>
<p>For the final not freed
        memory reporting, define the <code>_MEMMGR_REPORT</code> macro. </p>
<p>
Currently, the stress memory allocator is defined not yet implemented, and just
  redirects to standard malloc. To switch on stress allocation, define the <code>STRESS_MALLOC</code> macro.
    <p>
The memory management module cannot use port logging because it leads to infinite
  recursion. Its own primitive logging system uses the file in the current directory
  with name <code>malloc.log</code> for
  both logging and reporting. A different file name and location can be defining <code>MALLOC_LOG_FILE_NAME</code>.
    <p>
Used memory could be obtained by means of the <code>java.lang.management</code> interface.
It is presented as non-heap memory pool with name <code>Native Memory Pool</code>.
Different pool name could be set by redefining <code>NATIVE_POOL_NAME</code>.


    <h3>4. Build system</h3>

Currently we reuse VM build system. <br>
TODO - document platform defines and macros.

<h3>5. APR issues </h3>
<ul>
<li>	Non-buffered file I/O on Windows* OS has bad support for <code>apr_file_eof()</code>
<li>	On Windows OS, <code>apr_dso_load()</code> fails on NULL path - 
		which is meant for obtaining a handle for the calling module itself
</ul>


</body>

</html>
